home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr18 / ozm100.zip / OZM.DOC next >
Text File  |  1993-05-27  |  22KB  |  519 lines
  1.  
  2. OZM 1.0 - OzCIS Mail Organizer                     Copyright (C) 1993 Todd Fiske
  3. ────────────────────────────────────────────────────────────────────────────────
  4.  
  5. Contents
  6.  
  7.    topic                              line     page
  8.    ──────────────────────────         ────     ────
  9.    overview                             36        1
  10.  
  11.    installation                         71        2
  12.    usage                                82        2
  13.       command line parameters           89        2
  14.  
  15.       examples                         138        3
  16.    reference                           169        3
  17.       cleanup                          170        3
  18.       duplicates                       185        3
  19.  
  20.       filename                         229        4
  21.       debug mode                       239        4
  22.  
  23.       EOF marker                       269        5
  24.       extensions                       288        5
  25.       lists                            296        5
  26.       output path                      313        5
  27.  
  28.       progress bars                    353        6
  29.       replace mode                     364        6
  30.       quiet mode                       381        6
  31.  
  32.       update mode                      403        7
  33.       work files                       430        7
  34.       work path                        447        7
  35.  
  36.    planned enhancements                467        8
  37.    disclaimer                          476        8
  38.    credits                             485        8
  39.    contact                             508        8
  40.  
  41. ────────────────────────────────────────────────────────────────────────────────
  42.  
  43. -- overview
  44.  
  45. OZM is an organizer for OzCIS CISMAIL files. Since CIS Mail is more of a
  46. "two-person" exchange rather than the multi-person nature of forum messages,
  47. the idea of threading doesn't really apply. Instead, the primary job is simply
  48. to put the individual messages in a reasonable order while removing duplicates.
  49.  
  50. OZM can be used to reorganize OzCIS's message, purge, and outbox save files,
  51. and files which contain various combinations thereof. The input file will be
  52. scanned for all messages, duplicates will be removed, message and subject lists
  53. created, and the output file will be created in order of subject, date, and
  54. time.
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64. Page 1
  65.  
  66. _66
  67.  
  68. OZM 1.0 - OzCIS Mail Organizer                     Copyright (C) 1993 Todd Fiske
  69. ────────────────────────────────────────────────────────────────────────────────
  70.  
  71. -- installation
  72.  
  73. OZM.EXE should be put in a subdirectory that is named in your path statement.
  74. This allows it to be run from your OzCIS directory, or from any directory where
  75. you may store message files.
  76.  
  77. This file (OZM.DOC) can be copied to the printer, or read online in any text
  78. editor or file viewer (such as LIST or AutoRead). Copy the .ZIP file to a
  79. floppy disk for safe keeping.
  80.  
  81.  
  82. -- usage
  83.  
  84. OZM is a command line utility. It reads an input file, processes it, and
  85. creates a new version on the disk. At least one parameter is required (the
  86. message filename), and there are several other optional parameters. If OZD is
  87. run without any parameters, a basic help screen will be displayed.
  88.  
  89.    -- command line parameters
  90.  
  91. Here is the command line format. Items in angle brackets are placeholders for
  92. the actual names you need to supply. Items in square brackets are optional.
  93.  
  94.    ozm <filename[.mes]> [debug|quiet] [lists] [replace|update] [work=<path>]
  95.       [output=<path>] [cleanup]
  96.  
  97. Brief descriptions are given here. For more details, refer to the entry for
  98. each item in the reference section.
  99.  
  100.    filename[.mes]  the input file - the extension .MES will be added if no
  101.                    extension is given and the filename as it is can't be found
  102.  
  103.    debug           causes the program to produce more on-screen detail during
  104.                    the process, and to save copies of the work files
  105.  
  106.    quiet           causes the program to suppress most on-screen detail - if
  107.                    both DEBUG and QUIET modes are specified, DEBUG mode takes
  108.                    precedence
  109.  
  110.    lists           causes the program to generate message and subject lists
  111.  
  112.    work=<path>     allows you to specify a path where the work files will be
  113.                    placed
  114.  
  115.    output=<path>   allows you to specify a path where the output and list files
  116.                    will be placed
  117.  
  118.    replace         causes the program to replace the original input file with
  119.                    the new output file
  120.  
  121.    update          causes the program to exchange the names of the original and
  122.                    new files - if both REPLACE and UPDATE modes are specified,
  123.                    REPLACE mode takes precedence
  124.  
  125.    cleanup         causes the program to delete the work files when done
  126.  
  127. The filename must be the first parameter on the line. All other parameters can
  128. be specified in any order.
  129.  
  130. Page 2
  131.  
  132. _132
  133.  
  134. OZM 1.0 - OzCIS Mail Organizer                     Copyright (C) 1993 Todd Fiske
  135. ────────────────────────────────────────────────────────────────────────────────
  136.  
  137. -- usage, cont'd.
  138.    -- examples
  139.  
  140.    ozm cismail
  141.  
  142. This reads the file CISMAIL.MES in the current subdirectory, produces all work
  143. files in the current subdirectory, and creates the output file CISMAIL.001,
  144. also in the current subdirectory. Screen display is normal, and the work file
  145. will be left after the program finishes.
  146.  
  147.  
  148.    ozm sav\cismail.obs quiet lists work=e:\ cleanup
  149.  
  150. This will read the file CISMAIL.OSB in the SAV subdirectory beneath the current
  151. level. The output file will be written to the same subdirectory, along with the
  152. message and subject lists. The work file will be created in the root of drive
  153. E: which may be a RAM drive. They will be deleted when the program finishes.
  154. Most screen output will be supressed.
  155.  
  156.  
  157.    ozm cismail.sav debug lists work=e:\work output=e:\out replace >> ozm.out
  158.  
  159. The file CISMAIL.SAV will be read from the current subdirectory. The process
  160. will run, providing increased process information and writing temporary work
  161. files to disk. The output file will be created in the OUT subdirectory of drive
  162. E:, along with the message and subject lists. The work files will be created in
  163. the WORK subdirectory of drive E:. After the file CISMAIL.001 is created in
  164. E:\OUT, it will be copied back into the current subirectory, its name swapped
  165. with CISMAIL.SAV, and the original file will be deleted. All program output
  166. will be appended to the file OZM.OUT.
  167.  
  168.  
  169. -- reference
  170.    -- cleanup
  171.  
  172. The CLEANUP option tells OZM to delete the intermediate work file when the
  173. program is finished. In normal circumstances (ie, not in DEBUG mode), there is
  174. only one such file: <in_name>.TBL. It will either be placed in the same
  175. subdirectory as the input file, or in the subdirectory specified by the WORK=
  176. option.
  177.  
  178. Presently, there is no need to keep this after the output file has been
  179. created, so CLEANUP is a handy way to get rid of it. However, I've left it as
  180. an option since it could be useful for debugging purposes, and might be
  181. interesting to look at if your curious. See "work files" below for more
  182. information.
  183.  
  184.  
  185.    -- duplicates
  186.  
  187. OZM will scan the input file for duplicate messages to exclude from the final
  188. output. In my initial work, I simply scanned for duplicate occurences of
  189. SUBJECT+DATE+TIME. However, this turned up many records that were not actual
  190. duplicates. Indeed, since CIS doesn't include the number of seconds in the
  191. message post time, its possible for one person to write two (or more) messages
  192. in the space of one minute. What is far less likely though is that the length
  193. of those two messages will be the same. I use this fact to distinguish two
  194. messages that would otherwise appear to be the same based on the header alone.
  195.  
  196. Page 3
  197.  
  198. _198
  199.  
  200. OZM 1.0 - OzCIS Mail Organizer                     Copyright (C) 1993 Todd Fiske
  201. ────────────────────────────────────────────────────────────────────────────────
  202. -- reference, duplicates, cont'd.
  203.  
  204. In ordinary operation, OZM will create the header table, create the primary
  205. index, scan for duplicates, and produce the output file and lists excluding the
  206. duplicate records. However, if you think that OZM is excluding a record that is
  207. not an actual duplicate, I've included features in the program to allow you to
  208. backtrack and find out exactly. When run with the DEBUG command line option,
  209. OZM will create its additional work files. Firstly, look at <in_name>.DUP to
  210. see just exactly which records OZM considers to be duplicates. Find your
  211. "missing" message by its header and make a note of the record number. It should
  212. appear directly beside a message with the same header and size that is not
  213. deleted. Then take a look at <in_name>.DBG, or go directly to the original file
  214. (hopefully you didn't run with the REPLACE option), and find each message to
  215. compare them.
  216.  
  217. Most likely, if a message is deleted, its because the message has exactly as
  218. many characters as the other message with the same header. The solution is to
  219. edit the message file itself, and either add or delete one or two characters -
  220. anything but spaces, which OZM ignores. For example, add an extra period
  221. somewhere, or a comma, or something relatively innocuous. This will change the
  222. message size count enough for OZM to consider it to be unique. Run OZM again on
  223. the fixed-up file, and your message should come through just fine.
  224.  
  225. If on the other hand, the message seems to have been wrongly flagged as a
  226. duplicate, please contact me with the details.
  227.  
  228.  
  229.    -- filename
  230.  
  231. The filename must be the first parameter after the program name on the command
  232. line. If the name as entered is not found, and there is no extension, the
  233. extension .MES will be added and the program will try to find it again. If it
  234. still can't be found, the program will return to DOS with an error message. The
  235. path of the input filename will be used as the default path for work and output
  236. files if these options are not specified.
  237.  
  238.  
  239.    -- debug mode
  240.  
  241. In DEBUG mode, the program displays more information than usual during each
  242. step of the process. For some steps, the difference is not very great, while in
  243. others quite a lot of additional information is produced. Most steps will
  244. simply show the value of a "dot" on the progress bar. The one exception is
  245. during the step "creating output file". Instead of a progress bar, an
  246. indication of activity of the internal cache will be displayed. Every time a
  247. message is read from the input file into the cache, an "r" will be printed.
  248. Every time the cache is written to the output file, a "W" will be printed.
  249.  
  250. Additionally, DEBUG mode will cause OZM to write disk files of the main index
  251. at various stages in the process. Briefly, these files are:
  252.  
  253.    <in_name>.DBG - text file listing of the header file <in_name>.TBL
  254.    <in_name>.IND - the index file in binary format
  255.    <in_name>.DUP - text file listing of the header file in index order, showing
  256.                    which records OZM considers to be duplicates
  257.  
  258. If both DEBUG and QUIET modes are specified, DEBUG mode takes precedence. It is
  259. assumed that if you want additional screen information, then you don't really
  260. want suppressed screen information.
  261.  
  262. Page 4
  263.  
  264. _264
  265.  
  266. OZM 1.0 - OzCIS Mail Organizer                     Copyright (C) 1993 Todd Fiske
  267. ────────────────────────────────────────────────────────────────────────────────
  268.  
  269.    -- EOF marker
  270.  
  271. When the program starts, the first thing it does is to look for an End Of File
  272. (EOF) marker at the end of the input file. If one is found, it is replaced with
  273. a space character.
  274.  
  275. EOF markers can be added to files by some text editors, and also when files are
  276. concatenated (appended together) with the DOS COPY command, unless the /B
  277. switch is used.
  278.  
  279. OZM itself has no problems with EOF markers, but OzCIS does. A typical scenario
  280. might go like this: OZM reads a file with an EOF marker at the end of the last
  281. message. This message after reorganizing will most likely be moved to somewhere
  282. within the file, taking the EOF marker with it. Later, when OzCIS tries to read
  283. the file, it will effectively be truncated the file at that point. Its also
  284. possible that other undesired consequences could occur. Hence, OZM removes the
  285. EOF marker if found.
  286.  
  287.  
  288.    -- extensions
  289.  
  290. The output message file is always given a numbered extension. The first such
  291. output file in a directory will receive the extension .001, the second will be
  292. .002, and so on. It is hoped that one never has 999 such files in one
  293. subdirectory, although it is possible!
  294.  
  295.  
  296.    -- lists
  297.  
  298. OZM will create two output lists that give an overview of the messages and
  299. subjects within the output file. The subject summary list shows all subjects in
  300. the file, in subject order, with a count of all related messages, date and
  301. time, "seen" status, and sender name. The message list shows all messages in
  302. each subject, with date and time, "seen" status, and sender name.
  303.  
  304. The lists are simple text files that can be viewed in any text editor or file
  305. viewer (like LIST or AutoRead), or can be copied to a printer. They contain no
  306. control characters, although they may contain Character 251, the checkmark. The
  307. subject summary list is 89 characters wide. This should just squeeze into most
  308. narrow column printers if you mess around with the left margin and the
  309. characters-per-inch setting. The message list is 79 characters wide which
  310. should be easily printable without any additional hoop-jumping.
  311.  
  312.  
  313.    -- output path
  314.  
  315. An output path can be specified to tell OZM to put the output files in a
  316. directory different from the one where the input file lives. Although OZM is
  317. not as likely to have to deal with very large files, it might still be
  318. convenient to put the output message file in another drive or directory.
  319.  
  320. Make sure the target drive has at least as much free space as the size of the
  321. input file. The output file will generally be smaller than the input file, but
  322. its best to leave a little extra room. Also, if you specify the LISTS option,
  323. these get placed in the output path as well, so even more space will be
  324. necessary.
  325.  
  326.  
  327.  
  328. Page 5
  329.  
  330. _330
  331.  
  332. OZM 1.0 - OzCIS Mail Organizer                     Copyright (C) 1993 Todd Fiske
  333. ────────────────────────────────────────────────────────────────────────────────
  334.  
  335. -- reference, cont'd
  336.    -- output path, cont'd.
  337.  
  338. The specific format of the OUTPUT= option is:
  339.  
  340.    output=<pathname>
  341.  
  342. For example
  343.  
  344.    output=e:\output          the OUTPUT subdirectory on drive E:
  345.    output=d:                 the current subdirectory on drive D:
  346.    output=out                the OUT subdirectory below the current directory
  347.  
  348. There should be no spaces either before or after the equal sign, or within the
  349. path name itself. The path name shouldn't include a trailing backslash except
  350. in the case of a root directory.
  351.  
  352.  
  353.    -- progress bars
  354.  
  355. OZM provides simple progress bars for most steps in the process. First a line
  356. of dashes is drawn to indicate "100%" of the completed process. Then as the
  357. process goes on, a line of periods is drawn on top of that. This gives both an
  358. indication that something is happening, and a rough idea of how near the
  359. process is to completion. The progress bars are not exact and sometimes
  360. continue for one or two dots beyond the length of the initial line of dashes.
  361. Its pretty close though.
  362.  
  363.  
  364.    -- replace mode
  365.  
  366. REPLACE mode causes OZM to replace the original input file with new output
  367. file. Basically, the entire UPDATE operation is performed, and then the
  368. original input file is deleted. See the UPDATE option for details on that part
  369. of the process.
  370.  
  371. Generally, its perfectly safe to use the REPLACE option, but it does completely
  372. delete the original file. If you're at all uneasy about this, either use just
  373. the UPDATE option to "move" the output file into the input directory and swap
  374. filenames, or don't specify either of these options, and your original input
  375. file will be left intact in name and content. Its always a good idea to make a
  376. backup in any case.
  377.  
  378. If both the REPLACE and UPDATE options are specified on the same command line,
  379. the REPLACE option will take precedence.
  380.  
  381.  
  382.    -- quiet mode
  383.  
  384. In this mode, OZM will suppress most screen output with the exception of the
  385. major process labels. This makes for a much cleaner display, at the expense of
  386. knowing exactly where to look if the process runs afoul. It may even provide
  387. slightly better performance, but only marginally so.
  388.  
  389. DEBUG mode takes precedence over QUIET mode if both are specified. See "debug
  390. mode" above for more information.
  391.  
  392.  
  393.  
  394. Page 6
  395.  
  396. _396
  397.  
  398. OZM 1.0 - OzCIS Mail Organizer                     Copyright (C) 1993 Todd Fiske
  399. ────────────────────────────────────────────────────────────────────────────────
  400.  
  401. -- reference cont'd,
  402.  
  403.    -- update mode
  404.  
  405. UPDATE mode will move the newly created output file back into the input file
  406. subdirectory (if not already there), and will swap the names of the input and
  407. output files. This has the effect of leaving the new file with the original
  408. input file name, and the original file with a numbered extension name.
  409.  
  410. The process of moving the output file will depend on several things. If no
  411. OUTPUT= drive or path was specified (ie, the output file is in the same
  412. directory), then nothing needs to happen. If the output file is on the same
  413. drive, but in a different directory, the file will be moved via the DOS Rename
  414. service - all that is actually moved is the filename. If the output file is on
  415. another drive, the file will have to be copied into the input subdirectory, and
  416. deleted from its original position.
  417.  
  418. If a file with the same name as the output file already exists in the input
  419. file directory, you will be asked to confirm overwriting it. If you don't
  420. confirm this, the program will finish and exit to DOS to allow you to clean
  421. things up for yourself. Otherwise, the same named file will be deleted, and the
  422. new output file will be transferred.
  423.  
  424. Once the output file has been moved to the input file subdirectory, OZM will
  425. swap their filenames. The input file is first renamed to &&OZM&&.TMP, the ouput
  426. file is given the input file name, and finally, the input file is given the
  427. output file name.
  428.  
  429.  
  430.    -- work files
  431.  
  432. OZM creates at least one intermediate work file in all circumstances, and will
  433. create a few more if the DEBUG option is used. Here's a list of the work files
  434. - each one uses the name of the input file:
  435.  
  436.    always created
  437.    --------------------------------------------------------------------------
  438.    .TBL  message header table
  439.  
  440.    created with DEBUG option
  441.    --------------------------------------------------------------------------
  442.    .DBG  text file listing of *.TBL
  443.    .IND  binary index file for *.TBL (subject + date + time + message_size)
  444.    .DUP  text file listing of .IND showing where OZM has found duplicates
  445.  
  446.  
  447.    -- work path
  448.  
  449. A work path can be specified to tell OZM to put the intermediate work files in
  450. a directory different from the one where the input file lives. Since OZM uses a
  451. largely memory-based file system, speedy disk access isn't as crucial, so this
  452. option is provided primarily for the sake of keeping your files organized.
  453.  
  454. The format of the WORK= option is identical to that of the OUTPUT= option. See
  455. the "output path" section above for more information.
  456.  
  457.  
  458.  
  459.  
  460. Page 7
  461.  
  462. _462
  463.  
  464. OZM 1.0 - OzCIS Mail Organizer                     Copyright (C) 1993 Todd Fiske
  465. ────────────────────────────────────────────────────────────────────────────────
  466.  
  467. -- planned enhancements
  468.  
  469.    >> more intelligent handling of Executive News Service reports
  470.    >> ability to sort output by sender name and/or user id
  471.    >> accomodations for Internet email if such are necessary
  472.  
  473. Please feel free to make suggestions regarding what you'd like to see this
  474. program do, or how it should operate.
  475.  
  476.  
  477. -- disclaimer
  478.  
  479. This software performs its stated functions adequately, but you still use it at
  480. your own risk. I make no warranty as to the fitness of this program for a
  481. particular purpose. I will not be held liable for any damages arising from the
  482. use, misuse, or inability to use this software, even if I'm aware of the
  483. possibility of such.
  484.  
  485.  
  486. -- credits
  487.  
  488. OZM was primarily inspired by OZT user Rory Gordon after discovering that OZT
  489. wouldn't work with CIS Mail files. Additional motivation came from numerous
  490. other requests for a similar utility found while perusing the OzCIS Section.
  491.  
  492. OZM was written in The Semware Editor 1.0 (pre-release) by Semware, compiled
  493. with Turbo Pascal 7.0 by Borland, with additional support fron the Topaz 4.0
  494. libraries by Software Science.
  495.  
  496. Eternal gratitude goes to Steve Sneed for bringing OzCIS to the world.
  497.  
  498.  
  499. -- "ware" category, distribution
  500.  
  501. OZM is free. If you are driven to provide compensation, I will not refuse it!
  502. Email, postcards, and other correspondence are always appreciated. Feel free to
  503. make copies of OZM to give to friends and/or associates, but please distribute
  504. with all files intact and unchanged: OZM.EXE, OZM.DOC, and READ__ME.TXT.
  505. However, please do not charge any money for it, including disk-copying costs.
  506. For the time being, OZM is "give-a-ware".
  507.  
  508.  
  509. -- contact
  510.  
  511. If you have any problems, comments, suggestions, criticism, flames, etc, I can
  512. be reached as follows:
  513.  
  514.    Todd Fiske
  515.    PO Box 9715-244                     CompuServe : 70451,1424
  516.    Portland ME 04104-2000              Delphi     : TFISKE
  517.  
  518. Page 8 <eof:ozm.doc>
  519.